docs: Update AGENTS.md #20
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- add comprehensive agent handbook covering overview, structure, and workflows - document critical rules, playbooks, and references for all services
Author
Completed Working on "Auto PR Description"✅ Workflow completed successfully. |
Author
Completed Working on "Code Review"✅ Workflow completed successfully. |
![overcut-ai[bot]](https://avatars.githubusercontent.com/in/1367736?s=60&v=4){kind=small}
Author
There was a problem hiding this comment.
Summary:
- Findings: 0 BLOCKER / 0 CRITICAL / 2 MAJOR / 0 MINOR / 0 SUGGESTION / 0 PRAISE.
Key themes:
- AGENTS.md overstates the availability of docker/prisma/db flows in ecommerce-admin, so the guide no longer matches the package.json reality.
- Frontend testing instructions cite React Testing Library even though the necessary dependencies and npm scripts are absent.
Next steps:
- Either scope those scripts to the NestJS services in AGENTS.md or add equivalent scripts/documentation to ecommerce-admin.
- Add the React Testing Library dependencies and test script to ecommerce-admin (or update the guide to explain that frontend tests are not configured yet).
| ## ⚙️ Development Guidelines | ||
| - **Environment setup:** Follow each service README to copy `.env` files and adjust ports, database URLs, and JWT secrets. Admin UI expects `PORT` (default `3001`) and `REACT_APP_SERVER_URL`; servers require DB credentials, `BCRYPT_SALT`, and JWT settings. | ||
| - **Prerequisites:** Ensure Node.js ≥16, npm, and Docker are installed before running scripts. Kafka/MySQL/PostgreSQL containers are provisioned via the provided `docker-compose` files. | ||
| - **Scripts:** Every service documents the standard flow—`npm install`, `npm run prisma:generate` (servers), `npm run docker:dev`, `npm run db:init`, and `npm run start`. Containerized runs use `npm run compose:up` / `compose:down`. |
Author
There was a problem hiding this comment.
[major]: AGENTS.md L40-L44
@@
- Scripts: Every service documents the standard flow—
npm install,npm run prisma:generate(servers),npm run docker:dev,npm run db:init, andnpm run start. Containerized runs usenpm run compose:up/compose:down.
@@
apps/ecommerce-admin/package.json L15-L19
@@
"scripts": {
"start": "vite",
"build": "vite build",
"serve": "vite preview",
@@
The admin client exposes only the Vite dev/build scripts shown above—there are noprisma:*,docker:dev,db:init, orcompose:*commands—so the guide over-promises what "every service" offers. Please either clarify that only the NestJS servers expose those flows or add equivalent scripts/documentation for ecommerce-admin.
Suggested fix: Clarify that the docker/prisma/db flows apply only to the NestJS services or add the missing scripts to apps/ecommerce-admin.
| - `auth-provider/` implements login/logout/token refresh while `data-provider/` wraps `ra-data-graphql-amplication` for GraphQL calls typed via `src/types.ts`. | ||
| - `src/util/` mirrors backend filter DTOs so list pages can build GraphQL query arguments without re-defining shapes. | ||
| - Styling lives in `App.scss`, `theme/`, and resource-specific Sass modules; Vite handles bundling with `vite.config.ts`. | ||
| - Testing hooks follow the CRA-to-Vite migration defaults (`setupTests.ts`, React Testing Library) while lint/format scripts enforce Prettier + ESLint baselines. |
Author
There was a problem hiding this comment.
[major]: AGENTS.md L58-L62
@@
- Styling lives in
App.scss,theme/, and resource-specific Sass modules; Vite handles bundling withvite.config.ts. - Testing hooks follow the CRA-to-Vite migration defaults (
setupTests.ts, React Testing Library) while lint/format scripts enforce Prettier + ESLint baselines.
@@
apps/ecommerce-admin/package.json L5-L12
@@
"dependencies": {
"@apollo/client": "3.6.9",
"graphql": "15.6.1",
@@
apps/ecommerce-admin/package.json L16-L19
@@
"scripts": {
"start": "vite",
"build": "vite build",
"serve": "vite preview",
@@
The guide tells agents to rely on React Testing Library, yet the admin package declares no@testing-library/*dependencies and even lacks annpm testscript, so those instructions cannot be executed. Please add the missing dependencies/scripts or explain that frontend tests are not currently wired up.
Suggested fix: Add the React Testing Library packages plus an npm test script (or update AGENTS.md to state that frontend tests are not available).
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Why
Keeping AGENTS.md current ensures agents understand the architecture, workflows, and expectations before making automated changes, which improves reliability and consistency.
Summary
This PR adds a comprehensive AGENTS.md to guide automated contributors across the sample-app monorepo. The document explains the ecommerce/logistics services, repository structure, development workflows, and critical rules so agents can operate consistently and accurately.
Changes
Commits
Testing